home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / p_man / catD / xtalk.z / xtalk
Encoding:
Text File  |  2001-04-17  |  9.2 KB  |  265 lines
  1.  
  2.  
  3.  
  4. xxxxttttaaaallllkkkk((((DDDD3333))))                                                            xxxxttttaaaallllkkkk((((DDDD3333))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _x_t_a_l_k - IRIX XIO Infrastructure
  10.      _x_w_i_d_g_e_t__d_r_i_v_e_r__r_e_g_i_s_t_e_r - claim a class of XIO widgets
  11.      _x_w_i_d_g_e_t__d_r_i_v_e_r__u_n_r_e_g_i_s_t_e_r - remove driver from registry
  12.      _x_t_a_l_k__i_t_e_r_a_t_e - revisit all claimed widgets
  13.  
  14. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  15.      #include <sys/xtalk/xtalk.h>
  16.  
  17.      int
  18.      xwidget_driver_register(
  19.           xwidget_part_num_t _p_a_r_t__n_u_m,
  20.           xwidget_mfg_num_t _m_f_g__n_u_m,
  21.           char *_d_r_i_v_e_r__p_r_e_f_i_x,
  22.           unsigned _f_l_a_g_s);
  23.  
  24.      void
  25.      xwidget_driver_unregister(char *_d_r_i_v_e_r__p_r_e_f_i_x);
  26.  
  27.      void
  28.      xtalk_iterate(
  29.           char *_d_r_i_v_e_r__p_r_e_f_i_x,
  30.           xtalk_iter_f *_f_u_n_c)
  31.  
  32.    AAAArrrrgggguuuummmmeeeennnnttttssss
  33.      _p_a_r_t__n_u_m and _m_f_g__n_u_m
  34.              are the values that the XIO-based device will present in its XIO
  35.              ID register as identification.
  36.  
  37.      _d_r_i_v_e_r__p_r_e_f_i_x
  38.              is the prefix string for the driver's standard functions; the
  39.              infrastructure will use this prefix to locate the driver's cdevsw
  40.              entry, in order to call the driver's attach and detach routines.
  41.  
  42.      _f_l_a_g_s   Normally passed as zero.
  43.  
  44. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  45.      _x_t_a_l_k is the package that drivers for XIO-based devices use to set up
  46.      services for their devices.  These services include:
  47.  
  48.      +o   locating all instances of the device in the system (documented in
  49.          this page).
  50.  
  51.      +o   constructing CPU addresses that the driver can use to do PIO accesses
  52.          to the device (see _x_t_a_l_k__p_i_o(D3)).
  53.  
  54.      +o   constructing XIO addresses that the device can use to do DMA accesses
  55.          to memory (see _x_t_a_l_k__d_m_a(D3)).
  56.  
  57.      +o   arranging for a function to be called when the device requests
  58.          interrupt service (see _x_t_a_l_k__i_n_t_r(D3)).
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. xxxxttttaaaallllkkkk((((DDDD3333))))                                                            xxxxttttaaaallllkkkk((((DDDD3333))))
  71.  
  72.  
  73.  
  74.      +o   arranging for a function to be called when an error occurs during PIO
  75.          to, or DMA from the device (see _x_t_a_l_k__e_r_r_o_r(D3)).
  76.  
  77.      +o   accessing useful fields in some otherwise opaque data structures (see
  78.          _x_t_a_l_k__g_e_t(D3)).
  79.  
  80.    DDDDrrrriiiivvvveeeerrrr RRRReeeeggggiiiissssttttrrrraaaattttiiiioooonnnn
  81.      _x_w_i_d_g_e_t__d_r_i_v_e_r__r_e_g_i_s_t_e_r() is used by drivers to inform the infrastructure
  82.      that they are interested in certain XIO-based devices; a relation is kept
  83.      associating the specified part and manufacturer ID numbers with the noted
  84.      device driver prefix.  The infrastructure will call the attach routine
  85.      with that driver prefix, passing the hardware graph connection point
  86.      vertex as the only parameter.  This _c_o_n_n_e_c_t_i_o_n _p_o_i_n_t is then used in most
  87.      calls to the infrastructure to identify which particular XIO device is of
  88.      interest.
  89.  
  90.      Loadable device drivers should call this function from their _r_e_g() entry
  91.      point.  Drivers that are prelinked into the kernel should also make the
  92.      call from _r_e_g() for consistency, but may call from _i_n_i_t() if necessary.
  93.  
  94.      Device drivers may make multiple calls with different vendor and device
  95.      ID numbers, representing several compatible XIO devices.
  96.  
  97.      Wildcard values _X_W_I_D_G_E_T__P_A_R_T__N_U_M__N_O_N_E and _X_W_I_D_G_E_T__M_F_G__N_U_M__N_O_N_E may be
  98.      used if cards from any vendor or cards with any device code are of
  99.      interest; if both vendor and device are wildcarded, the attach routine
  100.      will be called for every XIO device connected to the system.
  101.  
  102.      When a loadable device driver calls _x_w_i_d_g_e_t__d_r_i_v_e_r__r_e_g_i_s_t_e_r(), the calls
  103.      to the driver's _a_t_t_a_c_h() function may occur before the infrastructure
  104.      returns control to the caller.  On some large systems, the _a_t_t_a_c_h() calls
  105.      may be executed by other threads and possibly on other processors,
  106.      concurrently with continued execution of the _r_e_g() function.
  107.  
  108.      _x_w_i_d_g_e_t__d_r_i_v_e_r__u_n_r_e_g_i_s_t_e_r() should be called by any unloadable device
  109.      driver, from within the driver's _u_n_r_e_g() function.  This will trigger
  110.      calls to the driver's _d_e_t_a_c_h() entry point, and remove any references to
  111.      the driver from the registry table.
  112.  
  113.  
  114.  
  115.    CCCCoooonnnnnnnneeeeccccttttiiiioooonnnn PPPPooooiiiinnnntttt IIIItttteeeerrrraaaattttiiiioooonnnn
  116.      It is sometimes important for driver code to be able to go back and
  117.      revisit each connection point that was passed to its attach routine; the
  118.      best case for this is the disconnecting of interrupt and error handling
  119.      functions before unloading a driver, and the reconnecting of these
  120.      handlers after the driver is reloaded.  _x_t_a_l_k__i_t_e_r_a_t_e() provides a quick
  121.      mechanism to have a private function called with each connection point
  122.      that the infrastructure has matched with the specified driver.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. xxxxttttaaaallllkkkk((((DDDD3333))))                                                            xxxxttttaaaallllkkkk((((DDDD3333))))
  137.  
  138.  
  139.  
  140.      On large systems, the calls may take place in many separate threads on
  141.      many separate processors, so the function to be called needs to use
  142.      appropriate locking when accessing driver-global structures.
  143.  
  144.  
  145. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  146.      Here is how a typical driver might make use of these functions:
  147.  
  148.      static char             xiofoo_prefix[] = "xiofoo_";
  149.      static char         xiofoo_edge[] = "foo";
  150.  
  151.      xiofoo_init(void)
  152.      {
  153.           /* the first time through, we are not
  154.            * registered, so this is a no-op.
  155.            * after that, it triggers reload_me.
  156.            */
  157.           xtalk_iterate(xiofoo_prefix, xiofoo_reload_me);
  158.      }
  159.  
  160.      xiofoo_unload(void)
  161.      {
  162.           ...
  163.           xtalk_iterate(xiofoo_prefix, xiofoo_unload_me);
  164.           ...
  165.      }
  166.  
  167.      xiofoo_reg(void)
  168.      {
  169.           xwidget_driver_register(
  170.                XIOFOO_VENDOR_ID,
  171.                XIOFOO_DEVICE_ID,
  172.                xiofoo_prefix, 0);
  173.      }
  174.  
  175.      xiofoo_unreg(void)
  176.      {
  177.           xwidget_driver_unregister(xiofoo_prefix);
  178.      }
  179.  
  180.      xiofoo_reload_me(vertex_hdl_t conn)
  181.      {
  182.           vertex_hdl_t   vhdl;
  183.           xiofoo_soft_t  xiofoo_soft;
  184.  
  185.           if (GRAPH_SUCCESS !=
  186.                hwgraph_traverse(conn, xiofoo_edge, &vhdl))
  187.                     return;
  188.           xiofoo_soft = hwgraph_fastinfo_get(vhdl);
  189.           if (!xiofoo_soft)
  190.                return;
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. xxxxttttaaaallllkkkk((((DDDD3333))))                                                            xxxxttttaaaallllkkkk((((DDDD3333))))
  203.  
  204.  
  205.  
  206.          if (xiofoo_soft->intr)
  207.                xtalk_intr_connect(xiofoo_soft->intr,
  208.                     xiofoo_intr,
  209.                     xiofoo_soft);
  210.      }
  211.  
  212.      xiofoo_reload_me(vertex_hdl_t conn)
  213.      {
  214.           vertex_hdl_t   vhdl;
  215.           xiofoo_soft_t  xiofoo_soft;
  216.  
  217.           if (GRAPH_SUCCESS !=
  218.                hwgraph_traverse(conn, xiofoo_edge, &vhdl))
  219.                     return;
  220.  
  221.           xiofoo_soft = hwgraph_fastinfo_get(vhdl);
  222.           if (!xiofoo_soft)
  223.                return;
  224.  
  225.           if (xiofoo_soft->intr)
  226.                xtalk_intr_connect(xiofoo_soft->intr,
  227.                     xiofoo_intr,
  228.                     xiofoo_soft);
  229.      }
  230.  
  231.      xiofoo_unload_me(vertex_hdl_t conn)
  232.      {
  233.           vertex_hdl_t   vhdl;
  234.           xiofoo_soft_t  xiofoo_soft;
  235.  
  236.           if (GRAPH_SUCCESS !=
  237.                hwgraph_traverse(conn, xiofoo_edge, &vhdl))
  238.                     return;
  239.           xiofoo_soft = hwgraph_fastinfo_get(vhdl);
  240.           if (xiofoo_soft->intr)
  241.                xtalk_intr_disconnect(xiofoo_soft->intr);
  242.      }
  243.  
  244.  
  245.  
  246.  
  247. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  248.      xtalk_dma(D3), xtalk_error(D3), xtalk_get(D3), xtalk_intr(D3),
  249.      xtalk_pio(D3).
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.